Open topic with navigation

Using Lua in Q-SYS Overview

Control scripting uses the Lua.org programming language with extensions that allow it to control Q-SYS hardware and software. Refer to the Lua 5.3 Reference manual for complete information. The Q-SYS specific extensions to Lua are documented in the following sections. The book "Programming in Lua" is highly recommended for learning Lua.

For examples of solutions using scripting refer to the Scripting Solutions topic.

Control Script Engine v2

Q-SYS Designer 4.0 and higher uses what is called 'Control Scripting v2' to set it apart from Control Script blocks created with 3.3 and prior versions of Q-SYS (v1). Appearance-wise, the new Control Script Component looks and behaves in the same way as the old. But there is a major difference that won't be obvious until you are working on a script in the new block. We have not changed any aspects of the base Lua language from the Lua 5.2 version, which debuted in v3.1. In 'Scripting v2,' we have significantly simplified the Q-SYS extensions to Lua 5.2 to both make scripts more powerful, yet simpler to create. The changes are detailed in topics linked in the next section. The main difference in the UDP, HTTP, TCP Socket and Server and Serial extensions is that these are now Event-Based much like you may be accustomed to with attaching Lua scripts to local controls.

Control Script blocks from designs created with 3.3 and lower Q-SYS Desginer files will look identical to the way they appeared in 3.x, with the exception that they have a new property called, 'New Script Engine.' If this is left at the default value of 'No,' the script will run using the 3.1-3.3 Lua script engine--essentially 'grandfathering' the script into 4.x. This is to protect the scripting functionality for designs upgrading to 4.0. It is only necessary to change the 'New Script Engine' value to 'Yes' if you intend to convert the script to use the new Q-SYS methods. The general thought on upgrading scripts to the new engine is to leave the Script Block as is and transplant sections into a new v2 script block, allowing for easier debug. However, there is absolutely nothing wrong with continuing to use 'v1' Scripts in 4.0 as we will not discontinue their use.

Script v2 is used both inside the Control Script v2 component as well as the Scriptable Controls component.

Lua 5.3 Note: Starting with Q-SYS Designer 5.1, the Lua version used within the various script mechanisms has been upgraded to Lua 5.3. Scripts written using Q-SYS Designer 4.0 to 5.0 will continue to function in Lua 5.3 because it was compiled with the compatibility option, which means that any depreciated Lua 5.2 commands will continue to function in Lua 5.3. However, new scripts should use strictly 5.3 syntax.

The Q-SYS Extensions to Lua

The following topics are covered in individual topics (Where there has been a change or addition in the Scripting v2 Lua engine, you will see an asterisk):

Introduction

A Q-SYS control script is written in the Lua language, within Q-SYS designer, for the purpose of automatically accomplishing tasks or creating other control mechanisms by associating the control script with standard controls in the Schematic Elements of a Q-SYS design. The Control Script component allows you to write scripts to perform operations on values, positions, strings, colors and other metadata, and timing of controls in the Schematic Elements. An alternative scripting component is Scriptable Controls, which incorporates the functionality of both the Custom Controls component

• The Control Script component is defined, in the component Properties, by the number of inputs and outputs. The body of the script is written in the Control Script Control Panel.
• Control Scripts use an Event/EventHandler model. EventHandlers (functions) are attached to an Event. When that Event takes place, the EventHandler is invoked.
• EventHandlers can be attached to Control Input objects that are invoked when the value of the Control changes.
• Both the input and output objects are in arrays called Controls.Inputs and Controls.Outputs. Access to these objects is accomplished with the [] operator. For example, Controls.Inputs[1].Value gives you access to the value of the Control assigned to input 1.
• Q-SYS specific functions are capitalized, while native Lua functions are lower case (e.g. Q-SYS’ Timer.Start vs Lua’s math.abs)
• Code changes can be made in a Control Script without redeploying a design.  A yellow notification bar appears at the top of the Control Panel window alerting the user that code is out of sync with the running design.  Clicking the yellow bar allows the script to be updated without having to redeploy the design or interrupting audio.
• Statements entered in the main body of a script  (outside of functions) are executed when a design is deployed and when Control Scripts are updated in a running design.

Notes

Maximum Execution Error

The Maximum Execution Error is thrown when an individual call of a Lua function exceeds the maximum allowed number of CPU cycles. Infinite loops are the most common cause of this error. “Max execution limits exceeded” is displayed in the debug log when this error occurs.

Arrays

Lua Arrays are 1 based.